home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / jjbqc.zip / JJBGLOSS.DOC < prev    next >
Text File  |  1993-01-04  |  23KB  |  690 lines
  1.  
  2.  
  3.  
  4.  ****************************************************************************
  5.  *                                                                          *
  6.  *                                                                          *
  7.  *                           JJBGLOSS.DOC                                   *
  8.  *                                                                          *
  9.  *                                                                          *
  10.  *   Copyright (c) 1989, JJB. All rights reserved.                          *
  11.  *                                                                          *
  12.  *   Purpose:                                                               *
  13.  *                                                                          *
  14.  *      The purpose of the glossary is to explain the basic JJB functions   *
  15.  *      and how to use them.                                                *
  16.  *                                                                          *
  17.  *      In some cases, technically correct C jargon is replaced by words    *
  18.  *      the average person can understand.                                  *
  19.  *                                                                          *
  20.  *     JJB, 9236 church Rd suite 1082, Dallas, Tx 75231 (214) 341-1635      *
  21.  ****************************************************************************
  22.  
  23.  
  24.  
  25.  
  26. /****************************************************************************
  27.  *                                                                          *
  28.  *  functions in file:                                                      *
  29.  *                                                                          *
  30.  *       JJB.OBJ                JJBINPUT.OBJ              JJBDOLLR.OBJ      *
  31.  *    ---------------       ----------------------     -------------------  *
  32.  *                                                                          *
  33.  *     jjb_initalize()       input(                       input_dollar(     *
  34.  *     jjb_start()           input_num(                   enter_dollar(     *
  35.  *     group(                input_lnum(                                    *
  36.  *     option(               enter(                                         *
  37.  *     init(                 enter_num                                      *
  38.  *     leave(                enter_lnum(                                    *
  39.  *     help(                 Plus additional                                *
  40.  *     default()               functions which                              *
  41.  *     dosexit(                let you make your                            *
  42.  *     plus hidden             own functions.                               *
  43.  *       library functions                                                  *
  44.  *                                                                          *
  45.  *   The JJB quick library 'JJB.QLB'  contains the functions above.         *
  46.  *   The .bat file 'JJBGO.BAT' can be used to create 'JJB.QLB'              *
  47.  *                                                                          *
  48.  ****************************************************************************
  49.  
  50.  
  51.   The input functions above give you a trememdous amount of control over
  52.   input.  You can input alpha-numeric, integer numeric or long numeric. You
  53.   can even specify the number range the input must fall into in order to
  54.   be acceptable. The functions are explained in this glossary.
  55.  
  56.   The three enter functions make data entry very simple.  You can also
  57.   design your own enter functions.
  58.  
  59.  
  60.      * ------------------------------------------------------------*
  61.                jjb_initalize()
  62.      * ------------------------------------------------------------*
  63.  
  64.  
  65.   'jjb_initalize()' initalizes the entire JJB system. It should always
  66.   be the first function in every program you write.
  67.  
  68.   After jjb_initalize(), you may use any of the hidden JJB library,
  69.   see JJBREAD.ME for more on the hidden JJB library.
  70.  
  71.   example:
  72.  
  73.     main() {
  74.            jjb_initalize();
  75.  
  76.            jjb_setup();
  77.  
  78.            jjb_start();
  79.  
  80.         }
  81.  
  82.  
  83.      * ------------------------------------------------------------*
  84.                  jjb_setup()
  85.      * ------------------------------------------------------------*
  86.  
  87.  
  88.   'jjb_setup()' is the function to use for setting up all our program's
  89.   options. Place 'jjb_setup()' in your program.
  90.  
  91.  
  92.   Below is a list of functions you can use in jjb_setup():
  93.  
  94.     group(         to set up a new group
  95.     option(        to set up an option
  96.     funct(         to assign a function name to an option
  97.     init(          to assign a function for initalizing
  98.     leave(         to assign a function when leaving
  99.     help(          to assign a function to the F1 key
  100.     default_opt()  to label an option as the default option
  101.     dosexit(       to assign a function for exiting your program
  102.     set(           to change a JJB variable or switch setting
  103.     get(           to fetch a JJB variable or switch setting
  104.  
  105.   JJB allows you to see the setup if you set the SHOWSETUP_SW to true
  106.   before setting up your options.  Once setup is correct, you should
  107.   remove the instruction so that your final program does not show the
  108.   setup.
  109.  
  110.  
  111.      #include <jjbset.h>
  112.  
  113.      main() {
  114.         jjb_initalize();
  115.         jjb_setup();
  116.         jjb_start();
  117.      }
  118.  
  119.  
  120.      jjb_setup();
  121.     {       set(SHOWSETUP_SW,T);
  122.         group("Update");
  123.             option("Open a file");
  124.     }
  125.  
  126.  
  127.  
  128.  
  129.      * ------------------------------------------------------------*
  130.                   jjb_start()
  131.      * ------------------------------------------------------------*
  132.  
  133.   'jjb_start()' starts calling (executing) your program functions.
  134.  
  135.  
  136.   It is a continuous loop. Below is a simplified explanation:
  137.  
  138.   jjb_start() {
  139.       while (1)
  140.       {
  141.         execute the function initalizing the group
  142.         execute the function initalizing the option
  143.  
  144.       ---->     execute the function for the option.
  145.            (if new option is selected, do a long jump to here)
  146.  
  147.         execute the function leaving the option
  148.         execute the fucntion leaving the group.
  149.       }
  150.  
  151.       }
  152.  
  153.   Every group and option can be initalized and exited with a function.
  154.  
  155.   If the user of your program selects another option, JJB will do a
  156.   long jump back to this loop.
  157.  
  158.   The actual code for this function is 10 times more complicated, but
  159.   the logic is the same.
  160.  
  161.  
  162.   Every keypress in your program is monitored by JJB to see what
  163.   action should be taken.
  164.  
  165.   If the user of your program presses 'ALT' and selects an option, JJB:
  166.  
  167.          1. Does a long jump back to this loop.
  168.          2. Executes the leave( function for the option if any.
  169.          3. Executes the leave( function for the group if different.
  170.          4. Executes the init( function for the new group if different.
  171.          5. Executes the init( function for the new option if any.
  172.          6. Executes the function for the option selected.
  173.  
  174.  
  175.  
  176. * -------------------------------------------------------------------------*
  177.             group("  string  ")
  178. * -------------------------------------------------------------------------*
  179.  
  180.   void group(char *)
  181.  
  182.   Use 'group(' to start setting up a new group of options.
  183.  
  184.  
  185.   Here is an examples:     group("File");
  186.  
  187.  
  188.   The technical declaration for this function is 'void group(char *)'.
  189.   The void means that this function will not return anything when
  190.   it comes back. 'char *' means that when we go to this function,
  191.   it will immediately look to the stack expecting one address to be
  192.   there.
  193.  
  194.   The address points to one byte in memory. In C we call this a string
  195.   or character pointer.
  196.  
  197.  
  198.   Everytime you use this function, JJB will start a new group of options.
  199.  
  200.  
  201.  
  202.     You may have up to 10 groups.
  203.     Each group may have any number of options for a maximun of 50.
  204.     Group and option desciptions may be of any length with a
  205.         maximun of 1200 character for all.
  206.  
  207.  
  208.   You can not assign a function to a group. You can however assign
  209.   a function for initalizing the group and a function which will be
  210.   executed when leaving the group.
  211.  
  212.  
  213.  
  214. * -------------------------------------------------------------------------*
  215.              option("   string     ")
  216.              option("   string     ",DRAWLINE)
  217. * -------------------------------------------------------------------------*
  218.  
  219.  
  220.   void option(char *)
  221.   void option(char *,int)
  222.  
  223.   Use 'option(' to set up an option in your program.
  224.  
  225.  
  226.   Here are some examples:
  227.  
  228.           option("Description of this option")
  229.           option("Description of this option",DRAWLINE)
  230.           option("De's'cription of this option")
  231.           option("Description of this option  F6")
  232.  
  233.  
  234.   There are two acceptable prototypes for this function. Both
  235.   will set up an option. If you use ',DRAWLINE', JJB will draw a line
  236.   in the pull-down menu and separate the  option from the next one.
  237.   'JJBSHOW1.C' shows you an example of this.
  238.  
  239.  
  240.   If you do not identify a letter with ' ', JJB will use the first letter
  241.   of the option description. If the first letter is already being used,
  242.   JJB will assign the second letter and so on.
  243.  
  244.  
  245.   A function key from F2 thru F8 may be assigned to any option.
  246.   To assign a function key to an option, just place it at the end
  247.   of the option description as shown in the example above.
  248.  
  249.   From then on, anywhere in your program, if the user presses the
  250.   function key, your program will select that option.  See example
  251.   in file 'JJBSHOW1.C'.
  252.  
  253.  
  254. * -------------------------------------------------------------------------*
  255.             init(functionname)
  256.             leave(functionname)
  257. * -------------------------------------------------------------------------*
  258.  
  259.  
  260.   You can initalize each group and/or option with a function.
  261.  
  262.   You can leave each group and/or option with a function.
  263.  
  264.  
  265.   To assign an initalizing function to a group, use 'init(functionname)'
  266.   after 'group(' in jjb_setup().
  267.  
  268.   To assign a leaving function to a group, use 'leave(functionname)'
  269.   after 'group(' in jjb_setup().
  270.  
  271.  
  272.   To assign an initalizing function to an option, use 'init(functionname)'
  273.   after 'option(' in jjb_setup().
  274.  
  275.   To assign a leaving function to an option, use 'leave(functionname)'
  276.   after 'option(' in jjb_setup().
  277.  
  278.  
  279.  
  280.  
  281.   Here is an example:
  282.  
  283.     jjb_setup() {
  284.  
  285.           group("One");
  286.         init(init_one);
  287.         leave(leave_one);
  288.  
  289.             option("Update file");
  290.               funct(update_file);
  291.               init(init_updatefile);
  292.               leave(leave_updatefile);
  293.  
  294.           group("Two");
  295.       }
  296.  
  297.  
  298.  
  299.     init_one() {  printf("initalize group one \n");
  300.     leave_one() {  printf("leaving  group one \n");
  301.  
  302.     update_file() { printf("This is the option function.\n"); }
  303.  
  304.     init_updatefile() {  printf("initalize update file \n");
  305.     leave_updatefile() {  printf("leaving  update file \n");
  306.  
  307.  
  308.   'JJBSHOW3.C' gives you more examples.
  309.  
  310.  
  311. * -------------------------------------------------------------------------*
  312.             help(functionname)
  313. * -------------------------------------------------------------------------*
  314.  
  315.  
  316.   Use 'help(' to assign a help function to the 'F1' key.
  317.  
  318.  
  319.   Here is how to do it:
  320.  
  321.     -Write your help function.
  322.  
  323.     -Use 'help(functionname)' to assign the function name.
  324.  
  325.  
  326.   The example below shows you how to set up a help function and
  327.   then assign it to the F1 key in jjb_setup(). The example uses
  328.   some of the hidden JJB library for saving, clearing and restoring
  329.   the screen.
  330.  
  331.        my_help() {
  332.         vsave_screen();
  333.         vclr_screen();
  334.         loc(6,10);
  335.         printf("This is help text.")
  336.         loc(8,10);
  337.         printf("More help text.")
  338.         loc(10,10);
  339.         printf("Press any key ");
  340.         getch();
  341.         vrest_screen();
  342.         }
  343.  
  344.        jjb_setup() {
  345.  
  346.         help(my_help);      /* assign function my_help() to F1  */
  347.  
  348.  
  349.        }
  350.  
  351.  
  352.  
  353. * -------------------------------------------------------------------------*
  354.                default_opt()
  355. * -------------------------------------------------------------------------*
  356.  
  357.  
  358.   When JJB starts, it will begin executing the default option.
  359.   Use this function in jjb_setup() after the option you want to be
  360.   the default option.
  361.  
  362.  
  363.   If you do not assign a default option, JJB will use the first option
  364.   set up in jjb_setup().  In the example below, the default option
  365.   will be the second option in the second group "Communication Devices":
  366.  
  367.  
  368.   jjb_setup() {
  369.  
  370.          group("Update");
  371.         option("One");
  372.         option("Two");
  373.  
  374.  
  375.          group("Another");
  376.         option("Printer control");
  377.         option("Communications Devices");
  378.             default_opt();
  379.         option("Test Signals");
  380.  
  381.      }
  382.  
  383.  
  384.   You may place 'default_opt()' after any option.
  385.  
  386.   jjb_start() will start with the default option 'Communication Devices'.
  387.  
  388.  
  389.  
  390. * -------------------------------------------------------------------------*
  391.                  dosexit(
  392. * -------------------------------------------------------------------------*
  393.  
  394.   'F9' is reserved for exiting to DOS.
  395.  
  396.  
  397.   If you want a function you write to be executed when exiting your
  398.   program, write the function and assign the function name in jjbsetup()
  399.   as follows:
  400.  
  401.  
  402.     jjbsetup() {
  403.           dosexit(myexit);
  404.  
  405.     }
  406.  
  407.   myexit() { printf("\nPrint this message when you exit."); getch(); }
  408.  
  409.  
  410.  
  411.   You can disable the 'F9' feature so JJB will not exit your program.
  412.   To disable, set F9OFF_SW to true anywhere in jjb_setup() as follows:
  413.  
  414.  
  415.  
  416.     #include <jjbset.h>
  417.  
  418.  
  419.     jjb_setup() {
  420.  
  421.         set(F9OFF_SW,T);
  422.       }
  423.  
  424.  
  425.  
  426. /****************************************************************************
  427.  *                                                                          *
  428.  *                          input(                                          *
  429.  *                          input_num(                                      *
  430.  *                          input_lnum(                                     *
  431.  *                          input_dollar(                                   *
  432.  *                                                                          *
  433.  ****************************************************************************
  434.  
  435.  
  436.   JJB provides you with four medium functions you can use for input. All
  437.   of these functions input strings and return the address of the string.
  438.  
  439.   'input_num(' and 'input_lnum(' also edit the string being input to make
  440.   sure that the number entered falls within a from/to range.
  441.  
  442.   'input_dollar(' is a very special function which formats the dollar
  443.   as you are inputting it just like an adding machine.
  444.  
  445.  
  446.   Prototypes:    char * input(int)
  447.          char * input_num(int,int,int)
  448.          char * input_lnum(int,long,long)
  449.          char * input_dollar()
  450.  
  451.   examples:       char *sp;
  452.  
  453.           sp = input(20);
  454.  
  455.           sp = input_num(2,1,12);
  456.  
  457.           long l1 = 100;
  458.           long l2 = 999999;
  459.           sp = input_lnum(6,l1,l2);
  460.  
  461.           sp = input_dollar();
  462.  
  463.  
  464.   The first example returns the address of a string up to 20 characters in
  465.   length.  The second example returns the address of a two character string
  466.   which if converted to an integer can not be less than one or greater than
  467.   12.
  468.  
  469.  
  470.   The third example returns the address of a string which contains a long.
  471.  
  472.   The 'input' functions provided above should only be used when you can not
  473.   use the 'enter' functions explained below.  The 'enter' functions do
  474.   10 times more than the 'input' functions.
  475.  
  476.  
  477. /****************************************************************************
  478.  *                                                                          *
  479.  *                          enter(                                          *
  480.  *                          enter_num(                                      *
  481.  *                          enter_lnum(                                     *
  482.  *                          enter_dollar(                                   *
  483.  *                                                                          *
  484.  ****************************************************************************
  485.  
  486.  
  487.   The 'enter' functions are designed to input entire screens of data
  488.   and automatically update a data base master record with the input.
  489.   'JJBSHOW5.C' is a good example of this.
  490.  
  491.   Look at that file and notice that the first time through, JJB will
  492.   only display the data on the screen and not begin entering until
  493.   it comes to the 'etpr_start_with(int)' function.
  494.  
  495.   'eptr' stands for enter pointer.  Each 'enter('  increments this
  496.   pointer by one. If you press the 'UP' arrow, the pointer is decremented.
  497.   Only if data is actually entered, will JJB update the data file.
  498.  
  499.   The printed documentation shows you how you can create your own
  500.   'enter' functions using the file 'jjbinput.obj'.
  501.  
  502.  
  503. * -------------------------------------------------------------------------*
  504.       enter( row, col, "     string      ", char pointer, len)
  505. * -------------------------------------------------------------------------*
  506.  
  507.  
  508.   prototype:  enter(int,int, char *,  char *, int)
  509.  
  510.  
  511.   The 'enter(' function does the same thing as the 'input(' function; plus
  512.   it allows you to precede the input with a label which will be bright on
  513.   the screen and dimmed after entry. The enter function also copies the
  514.   input to the address referenced by the data address.
  515.  
  516.  
  517.         enter(8,0,"Enter your name",data address,44)
  518.  
  519.  
  520.   One of the big advantages about the 'input' and 'enter' functions is
  521.   that JJB monitors every keypress looking for the ALT key for changing
  522.   options, F1 for help, F9 for exiting your program, etc.
  523.  
  524.  
  525.   The enter function is a very high-level routine. It automatically updates
  526.   the data file. It is designed to be used for entering entire screens
  527.   of data. Below is how your input might look on the screen:
  528.  
  529.  
  530.         Enter your name: ______________________________
  531.  
  532.  
  533.   Here is a list of what the enter functions do:
  534.  
  535.         -Turn on bright intensity.
  536.         -Video fast the string at row and column.
  537.         -Turn on the input color for the input.
  538.         -Use the input( function to get the data.
  539.         -Look to see if the UP or DOWN ARROWS were pressed.
  540.         -Turn off bright intensity and turn off input color.
  541.         -Video fast the string and the input.
  542.         -Update the data address with the data you input.
  543.         -If '*' is pressed, clear data with null character.
  544.  
  545.  
  546.   The file JJBINPUT.OBJ also contains functions which allow you to make
  547.   your own enter functions. The printed documentation comes with many
  548.   examples showing you how easy it is to make your own enter routines.
  549.  
  550.  
  551.   Files 'JJBSHOW4.C' and 'JJBSHOW5.C' give you examples.
  552.  
  553.  
  554.  
  555. * -------------------------------------------------------------------------*
  556.       enter( row, col, "     string      ", char pointer, len, row,  col)
  557. * -------------------------------------------------------------------------*
  558.  
  559.  
  560.   prototype:  enter(int,int, char *,  char *, int, int, int )
  561.  
  562.   This is an extention of the previous enter function. You can place the
  563.   data being input anywhere on the video screen. In the example below,
  564.   JJB will input on row 12, column 20.
  565.       char data[31];
  566.  
  567.       enter( 10,  20,  "Enter your name: ",  &data[0],  30,  12,  20)
  568.  
  569.  
  570.         Enter your name:
  571.  
  572.         ______________________________
  573.  
  574.  
  575. * -------------------------------------------------------------------------*
  576.       enter_num( 10,  20,  "Enter month: ",     dp,        2,   1,  12)
  577.       enter_num( row, col, "  string    ", data pointer, len, from, to)
  578. * -------------------------------------------------------------------------*
  579.  
  580.  
  581.   prototype:  enter_num(int,int, char *,  char *, int, int, int)
  582.  
  583.  
  584.   Use 'enter_num(' to enter and edit integers.
  585.  
  586.  
  587.   'Enter_num(' is an extremely high-level function.  It is designed to
  588.   do everything for you automatically.  Use it to input integer
  589.   values. All values are input as strings but edited as integers and
  590.   they must fall within the from/to range in order to be acceptable.
  591.  
  592.   Eventually the full power of JJB will sink into you. Every keypress
  593.   is monitored in the entire system. In any 'enter' function, the
  594.   user can:
  595.  
  596.     -Press 'RET' and not change the data.
  597.     -Press 'ALT' and select another option.
  598.     -Press any assigned function key to change options.
  599.     -Press 'F1' for help.
  600.     -Press 'F9' for DOS exit.
  601.     -Press '*' to place blanks in the data string.
  602.     -Press 'UPARROW' to move up on the screen to the previous enter.
  603.     -Press 'DOWNARROW' or 'RETURN' to move down on the screen
  604.             to the next enter.
  605.     -Press 'CONTROL G' to put a programmers grid on the screen.
  606.  
  607.   The enter functions are designed to integrate with future JJB software
  608.   which will automatically update large data bases with very little
  609.   programming effort.
  610.  
  611.  
  612.  
  613. * -------------------------------------------------------------------------*
  614.   enter_num( 10,  20,  "Enter date: ",     dp,        2,   1,  12,  10, 32 )
  615.   enter_num( row, col, "  string    ", data pointer, len, from, to, row,col)
  616. * -------------------------------------------------------------------------*
  617.  
  618.  
  619.   prototype:  enter_num(int,int, char *,  char *, int, int, int, int, int)
  620.  
  621.  
  622.   This example is the same as the above except you may also send to this
  623.   function the row and column where you want the input to appear.
  624.  
  625.   Here is an example of entering a date:
  626.  
  627.   ent_date() {
  628.     char mo[3];
  629.     char day[3];
  630.     char yr[3];
  631.  
  632.     vloc(10,33);    vfs("  -  -  ");
  633.     enter_num(10, 20, "Enter date: ", &mo[0],  2, 1, 12, 10, 33)
  634.     enter_num(10, 20, "Enter date: ", &day[0], 2, 1, 31, 10, 36)
  635.     enter_num(10, 20, "Enter date: ", &yr[0],  2, 0, 99, 10, 39)
  636.     }
  637.  
  638.  
  639.   Below is how it could appear.
  640.  
  641.  
  642.             Enter date:  __-__-__
  643.  
  644.  
  645.  
  646. * -------------------------------------------------------------------------*
  647.    enter_lnum( row, col, "string", char pointer, len, lfrom, lto)
  648.    enter_lnum( row, col, "string", char pointer, len, lfrom, lto, row,col)
  649. * -------------------------------------------------------------------------*
  650.  
  651.  
  652.   The object file 'JJBINPUT.OBJ' also contains a function for entering long
  653.   numbers. Here is an example:
  654.  
  655.         long lfrom = 1;
  656.         long lto   = 999999;
  657.  
  658.         char ck[7];
  659.  
  660.         enter_lnum(10,20 "Enter check#: " ,&ck[0], 6, lfrom, lto)
  661.  
  662.   If you are not storing numbers as strings, you can convert the
  663.   string to a long number as follows: 'lnum = strtol(&ck[0]);'
  664.  
  665.  
  666.  
  667.  
  668. * -------------------------------------------------------------------------*
  669.        enter_dollar( row, col, "string", char pointer, irow, icol)
  670. * -------------------------------------------------------------------------*
  671.  
  672.  
  673.   This function allows you display a dollar amount from a data file and
  674.   enter a new amount updating the file with the new amount.
  675.  
  676.   The amount is entered as a string and formatted on the screen the same
  677.   way as an adding machine. Row and col refer to the place on the screen
  678.   you want "string" to appear. The dollar amount is input at irow and icol.
  679.  
  680.   The function 'input_dollar(' and 'enter_dollar(' and in the object
  681.   file: JJBDOLLR.OBJ. See JJBSHOW5.C for an example.
  682.  
  683.  
  684.  
  685.  
  686. * -------------------------------------------------------------------------*
  687.               end of: JJBGLOSS.DOC
  688. * -------------------------------------------------------------------------*
  689.  
  690.